test: Add additional MCP transport context integration tests by tzolov · Pull Request #529 · modelcontextprotocol/java-sdk

tzolov · 2025-09-02T16:16:17Z

Add integration tests for transport context propagation between MCP clients and servers
Test both sync and async server implementations across all transport types (stateless, streamable, SSE)
Cover Spring WebFlux and WebMVC environments with dedicated test suites
Validate context flow through HTTP headers for authentication, correlation IDs, and metadata
Rename existing McpTransportContextIntegrationTests to SyncServerMcpTransportContextIntegrationTests for clarity

This change adds missing test coverage for the MCP transport context feature, which allows passing contextual information (like authentication tokens, correlation IDs, or custom metadata) between MCP clients and servers through HTTP headers. The tests ensure that context propagation works correctly across:

Different server types (sync/async)
Different transport mechanisms (stateless, streamable, SSE)
Different Spring environments (WebFlux, WebMVC)
Different client types (sync/async)

Breaking Changes

None. This PR only adds new test files and renames one existing test file for clarity. No production code or APIs are changed.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update (in this case, test coverage which serves as usage documentation)

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

- Add integration tests for transport context propagation between MCP clients and servers - Test both sync and async server implementations across all transport types (stateless, streamable, SSE) - Cover Spring WebFlux and WebMVC environments with dedicated test suites - Validate context flow through HTTP headers for authentication, correlation IDs, and metadata - Rename existing McpTransportContextIntegrationTests to SyncServerMcpTransportContextIntegrationTests for clarity Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

Kehrlann

Nice and thorough work! We have a much better confidence in transports with this. Thanks.

I wonder if we don't have a structural issue with these tests, even though that existed before.

We always build all server transports as the field of classes. And then each test only calls .close() on the server that it is using, which in turns closes the underlying server transport - but other transports in the class never have their .close() called. Is that a problem, or will everything be magically garbage-collected away? Maybe @chemicL has insights for us.

(Also, if a test fails, mcpServer.close() is never called).

Kehrlann · 2025-09-02T19:41:31Z

...test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java

+	private static final ThreadLocal<String> CLIENT_SIDE_HEADER_VALUE_HOLDER = new ThreadLocal<>();
+
+	private static final String HEADER_NAME = "x-test";
+
+	private final Supplier<McpTransportContext> clientContextProvider = () -> {
+		var headerValue = CLIENT_SIDE_HEADER_VALUE_HOLDER.get();
+		return headerValue != null ? McpTransportContext.create(Map.of("client-side-header-value", headerValue))
+				: McpTransportContext.EMPTY;
+	};


[suggestion] I don't think we need to test sync clients and async clients. Sync clients are already tested with Sync servers ; hopefully all servers and all clients are spec-compliant, and breaking something in a client should result in an issue, now matter what type of server is used (and vice-versa). Otherwise the matrix starts to get quite big.

So I suggest:

SyncServer tests -> use sync clients

AsyncServer test -> use async clients

This way they are "naturally" paired - even though sync server + async client and async server + sync client would also work.

Kehrlann · 2025-09-02T19:42:11Z

...test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java

+	private final McpSyncHttpClientRequestCustomizer clientRequestCustomizer = (builder, method, endpoint, body,
+			context) -> {
+		var headerValue = context.get("client-side-header-value");
+		if (headerValue != null) {
+			builder.header(HEADER_NAME, headerValue.toString());
+		}
+	};


[suggestion] Let's use an async request customizer. It should change anything but serves as an example.

Kehrlann · 2025-09-02T19:47:04Z

...webmvc/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java

+	@Configuration
+	static class TestCommonConfig {
+
+		@Bean
+		public McpTransportContextExtractor<ServerRequest> serverContextExtractor() {
+			return (ServerRequest r) -> {
+				String headerValue = r.servletRequest().getHeader(HEADER_NAME);
+				return headerValue != null ? McpTransportContext.create(Map.of("server-side-header-value", headerValue))
+						: McpTransportContext.EMPTY;
+			};
+		};
+
+	}


[question] does this need to be a bean wrapped in a config class? It holds a static function that could be used "as-is".

Kehrlann · 2025-09-02T19:58:22Z

...webmvc/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java

+	private final McpSyncClient streamableClient = McpClient
+		.sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + PORT)
+			.httpRequestCustomizer(clientRequestCustomizer)
+			.build())
+		.transportContextProvider(clientContextProvider)
+		.build();


[suggestion] swap the order, the beans are between fields of this class.

Kehrlann · 2025-09-02T20:00:30Z

...webmvc/src/test/java/io/modelcontextprotocol/common/McpTransportContextIntegrationTests.java

+		var mcpServer = McpServer.sync(statelessServerTransport)
+			.capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
+			.tools(new McpStatelessServerFeatures.SyncToolSpecification(tool, statelessHandler))
+			.build();


[suggestion] Make the server a bean. This way, all the servery bits are in a config class.

Kehrlann · 2025-09-02T20:01:55Z

...test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java

+
+	// Async client context provider
+	ExchangeFilterFunction asyncClientContextProvider = (request, next) -> Mono.deferContextual(ctx -> {
+		var context = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);


[nit] clarify distinction between reactor context (ctx) and McpTransportContext

Suggested change

var context = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);

var transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);

Kehrlann · 2025-09-02T20:02:54Z

...test/java/io/modelcontextprotocol/common/AsyncServerMcpTransportContextIntegrationTests.java

+	private static final ThreadLocal<String> SYNC_CLIENT_SIDE_HEADER_VALUE_HOLDER = new ThreadLocal<>();
+
+	private static final String HEADER_NAME = "x-test";
+
+	// Sync client context provider
+	private final Supplier<McpTransportContext> syncClientContextProvider = () -> {
+		var headerValue = SYNC_CLIENT_SIDE_HEADER_VALUE_HOLDER.get();
+		return headerValue != null ? McpTransportContext.create(Map.of("client-side-header-value", headerValue))
+				: McpTransportContext.EMPTY;
+	};


Same comment as in AsyncServerMcpTransportContextIntegrationTests : consider using only async clients here.

…ove resource cleanup - Remove synchronous client tests from AsyncServerMcpTransportContextIntegrationTests - Clean up unused sync client imports and ThreadLocal context providers - Add proper resource cleanup for async clients in teardown methods - Update documentation to reflect async-only client/server focus - Refactor WebMVC tests to use Spring beans for MCP server configuration - Simplify test architecture by separating sync and async concerns Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

tzolov · 2025-09-03T16:01:36Z

@Kehrlann , thanks for the review!
Latest commit should address most of the recommendation.

Kehrlann · 2025-09-03T19:33:32Z

Looks good. Thanks for the updates!

tzolov added this to the 0.12.0 milestone Sep 2, 2025

Kehrlann reviewed Sep 2, 2025

View reviewed changes

tzolov merged commit 02b8c4b into modelcontextprotocol:main Sep 4, 2025
1 of 2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

test: Add additional MCP transport context integration tests#529

test: Add additional MCP transport context integration tests#529
tzolov merged 2 commits intomodelcontextprotocol:mainfrom
tzolov:mcp-transport-context-its

tzolov commented Sep 2, 2025

Uh oh!

Kehrlann left a comment •

edited

Loading

Uh oh!

Kehrlann Sep 2, 2025 •

edited

Loading

Uh oh!

Kehrlann Sep 2, 2025

Uh oh!

Kehrlann Sep 2, 2025

Uh oh!

Kehrlann Sep 2, 2025

Uh oh!

Kehrlann Sep 2, 2025

Uh oh!

Kehrlann Sep 2, 2025

Uh oh!

Kehrlann Sep 2, 2025

Uh oh!

tzolov commented Sep 3, 2025

Uh oh!

Kehrlann commented Sep 3, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	var context = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);
	var transportContext = ctx.getOrDefault(McpTransportContext.KEY, McpTransportContext.EMPTY);

Conversation

tzolov commented Sep 2, 2025

Breaking Changes

Types of changes

Checklist

Uh oh!

Kehrlann left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kehrlann Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kehrlann Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

Kehrlann Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

Kehrlann Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

Kehrlann Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

Kehrlann Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

Kehrlann Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

tzolov commented Sep 3, 2025

Uh oh!

Kehrlann commented Sep 3, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Kehrlann left a comment •

edited

Loading

Kehrlann Sep 2, 2025 •

edited

Loading